feat(xpkg): add --annotation flag to xpkg build and xpkg push by chaitanyapantheor · Pull Request #11 · crossplane/cli

chaitanyapantheor · 2026-05-12T05:34:34Z

Description of your changes

Adds a repeatable --annotation/-a KEY=VALUE flag to crossplane xpkg build
and crossplane xpkg push, allowing users to attach OCI manifest annotations
to packages at build or push time.

# Build with a static annotation
crossplane xpkg build -a org.opencontainers.image.source=https://github.com/org/repo

# Push with a dynamic (CI-injected) annotation
crossplane xpkg push -f pkg.xpkg \
  -a org.opencontainers.image.revision=$(git rev-parse HEAD) \
  xpkg.example.io/org/pkg:v1.0.0

Annotations are applied to the OCI image manifest. Malformed annotations
(missing =) return an error before any write or push occurs. Reading
annotations from crossplane.yaml is intentionally out of scope to avoid
silently propagating internal Crossplane annotations to the OCI registry.

Covered by unit tests in cmd/crossplane/xpkg/annotations_test.go.

Fixes crossplane/crossplane#7282

I have:

Read and followed Crossplane's [contribution process].
Run ./nix.sh flake check to ensure this PR is ready for review.
Added or updated unit tests.
Linked a PR or a [docs tracking issue] to [document this change].
Added backport release-x.y labels to auto-backport this PR.

coderabbitai · 2026-05-12T05:38:46Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8bba7570-7512-4063-91ba-83aeec134594

📥 Commits

Reviewing files that changed from the base of the PR and between 4476efa and a8a515b.

📒 Files selected for processing (5)

cmd/crossplane/xpkg/annotations.go
cmd/crossplane/xpkg/annotations_test.go
cmd/crossplane/xpkg/batch.go
cmd/crossplane/xpkg/build.go
cmd/crossplane/xpkg/push.go

🚧 Files skipped from review as they are similar to previous changes (5)

cmd/crossplane/xpkg/batch.go
cmd/crossplane/xpkg/annotations.go
cmd/crossplane/xpkg/annotations_test.go
cmd/crossplane/xpkg/push.go
cmd/crossplane/xpkg/build.go

📝 Walkthrough

Walkthrough

This PR adds support for setting OCI image annotations via --annotation/-a CLI flags on both crossplane xpkg build and crossplane xpkg push commands. Users supply annotations as key=value pairs, which are parsed, validated, and applied to the OCI image manifest before the image is finalized or pushed.

Changes

OCI Annotation CLI Support

Layer / File(s)	Summary
Annotation parsing and image application helpers `cmd/crossplane/xpkg/annotations.go`, `cmd/crossplane/xpkg/annotations_test.go`	Introduces `parseAnnotations` to convert repeatable `key=value` CLI arguments into a map with error handling for malformed entries, and `annotateImage` to apply annotations to OCI manifests. Test suite covers empty inputs, single/multiple entries, values containing `=`, and missing delimiters.
Build command annotation support `cmd/crossplane/xpkg/build.go`	Adds `--annotation/-a` repeatable flag to `buildCmd`, parses annotations during `Run()`, handles parse errors with `errParseAnnotations`, and applies annotations to the built image before digest computation and packaging.
Push command annotation support `cmd/crossplane/xpkg/push.go`	Adds `--annotation/-a` repeatable flag to `pushCmd`, parses annotations and passes them to `pushImages`. Updates `pushImages` signature to accept the annotations map and applies annotations to images in both single-package and concurrent multi-package push paths.
Batch retry wiring `cmd/crossplane/xpkg/batch.go`	Updates the retry loop's `pushImages` invocation to pass `nil` for the new annotations parameter.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

Setting OCI Annotations on artifacts produced from crossplane xkpg build/push commands crossplane#7282: Implements the requested feature to add OCI annotation support via --annotation/-a flags on crossplane xpkg build and crossplane xpkg push, exposing custom image metadata on the image manifest.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: adding an --annotation flag to xpkg build and push commands, meeting the 72-character requirement.
Description check	✅ Passed	The description is comprehensive, providing context, usage examples, scope boundaries, and test coverage, all directly related to the changeset.
Linked Issues check	✅ Passed	The PR implements the primary objective from `#7282` by adding a repeatable --annotation/-a flag to both xpkg build and xpkg push commands, enabling users to attach OCI annotations.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the --annotation flag feature; no extraneous modifications to unrelated functionality are present.
Breaking Changes	✅ Passed	All changes are to unexported types and functions in cmd/crossplane/xpkg. No exported public APIs were removed, renamed, or have required fields added. No breaking changes detected.
Feature Gate Requirement	✅ Passed	PR adds --annotation CLI flag to xpkg build/push. No apis/** changes, not experimental, purely additive. Feature gate requirement doesn't apply.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

Generate code and open pull requests
Plan features and break down work
Investigate incidents and troubleshoot customer tickets together
Automate recurring tasks and respond to alerts with triggers
Summarize progress and report instantly

Built for teams:

Shared memory across your entire org—no repeating context
Per-thread sandboxes to safely plan and execute work
Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Signed-off-by: Chaitanya Maili <chaitanya.maili@pantheon.io>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Chaitanya Maili <chaitanya.maili@pantheon.io>

adamwg

I've left a couple of thoughts, but overall this looks good to me and seems like a valuable feature.

adamwg · 2026-05-14T19:15:26Z

 	Package string `arg:"" help:"Where to push the package. Must be a fully qualified OCI tag, including the registry, repository, and tag." placeholder:"REGISTRY/REPOSITORY:TAG"`

 	// Flags. Keep sorted alphabetically.
+	Annotation            []string `help:"An OCI manifest annotation to add to the package in key=value format. Repeatable." placeholder:"KEY=VALUE" short:"a"`


I wonder if this should be OCIAnnotation / --oci-annotation or something like that to make it clear how it's different from the metadata.annotations.

adamwg · 2026-05-14T19:19:08Z

 				return errors.Wrapf(err, errAnnotateLayers)
 			}

+			img = annotateImage(img, annotations)


Should we apply the same annotations to the index (built below with mutate.AppendManifests)?

adamwg · 2026-05-14T19:21:43Z

@@ -0,0 +1,49 @@
+/*
+Copyright 2025 The Crossplane Authors.


Nit: 2026 :-)

chaitanyapantheor requested review from a team, jcogilvie and tampakrap as code owners May 12, 2026 05:34

chaitanyapantheor requested review from negz and removed request for a team May 12, 2026 05:34

chaitanyapantheor mentioned this pull request May 12, 2026

feat(xpkg): add --annotation flag and crossplane.yaml propagation to xpkg build/push crossplane/crossplane#7345

Closed

chaitanyapantheor and others added 4 commits May 12, 2026 15:02

feat(xpkg): add parseAnnotations helper for OCI manifest annotations

9f56eb5

Signed-off-by: Chaitanya Maili <chaitanya.maili@pantheon.io>

feat(xpkg): add --annotation flag to xpkg build

3c1ee22

Signed-off-by: Chaitanya Maili <chaitanya.maili@pantheon.io>

feat(xpkg): add --annotation flag to xpkg push

d29df87

Signed-off-by: Chaitanya Maili <chaitanya.maili@pantheon.io>

fix(xpkg): address golangci-lint issues in annotation support

a8a515b

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Chaitanya Maili <chaitanya.maili@pantheon.io>

chaitanyapantheor force-pushed the issues/7282 branch from 4476efa to a8a515b Compare May 12, 2026 09:33

adamwg reviewed May 14, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(xpkg): add --annotation flag to xpkg build and xpkg push#11

feat(xpkg): add --annotation flag to xpkg build and xpkg push#11
chaitanyapantheor wants to merge 4 commits into
crossplane:mainfrom
chaitanyapantheor:issues/7282

chaitanyapantheor commented May 12, 2026

Uh oh!

coderabbitai Bot commented May 12, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Uh oh!

adamwg left a comment

Uh oh!

adamwg May 14, 2026

Uh oh!

adamwg May 14, 2026

Uh oh!

adamwg May 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

chaitanyapantheor commented May 12, 2026

Description of your changes

Uh oh!

coderabbitai Bot commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Uh oh!

adamwg left a comment

Choose a reason for hiding this comment

Uh oh!

adamwg May 14, 2026

Choose a reason for hiding this comment

Uh oh!

adamwg May 14, 2026

Choose a reason for hiding this comment

Uh oh!

adamwg May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coderabbitai Bot commented May 12, 2026 •

edited

Loading